Description

Introduces pool-indexer service that indexes Uniswap V3 pool state from on-chain events and serves it over HTTP, plus the driver-side plumbing to use it as a drop-in replacement for the Uniswap V3 subgraph. The goal is to remove the driver's request-path dependency on external subgraphs.

How it works at a high level. Pool-indexer maintains a Postgres snapshot of every Uniswap V3 pool on the factories it's configured to watch. The lifecycle is:

1. Bootstrap (one-time per network, two options):

• Cold seed (used when no subgraph is available): runs in three phases.
  • Phase 1 — pool discovery: scan PoolCreated logs on the factory from genesis to current head, chunked ~10k blocks per eth_getLogs call with bisecting retry on "range too large" rejections. Sparse filter → cheap. Collects ERC-20 decimals() for every referenced token via concurrent eth_calls.
  • Phase 2 — state snapshot: for each discovered pool, concurrently fetch slot0() + liquidity() at the snapshot block. Populates (sqrt_price, tick, liquidity) for all pools.
  • Phase 3 — tick reconstruction: for pools with non-zero current liquidity, fetch their Mint/Burn log history using an address-filtered eth_getLogs (server-side-selective, cheap even over full history) and accumulate signed liquidity_net deltas per tick. Dead pools skip this phase. Persistence happens in pool-address-batch-sized chunks so memory stays bounded and operators see progress.
• Subgraph seed (used when a subgraph is available): single-shot pull of pools + ticks from the Uniswap V3 subgraph. Faster than cold seed for chains like mainnet where the subgraph is public and up-to-date.

2. Live indexing (continuous): once seeded, the indexer polls for new finalized blocks and processes them in chunks. For each chunk it fetches all V3-shaped events (PoolCreated, Initialize, Swap, Mint, Burn) in one eth_getLogs call — topic-filtered, no address filter (addresses of pools can't fit; the SQL
   writers filter unknown pools out instead). Within a single chunk transaction: new pools are inserted, Swap/Initialize events update pool state (they contain sqrtPrice/liquidity/tick in the event payload — free state), Mint/Burn adjust tick liquidity_net and trigger a pool.liquidity() refresh if no Swap was
   seen in the same chunk, and the checkpoint advances.
3. Async token-symbol backfill: symbol lookups are deliberately decoupled from the ingest hot path (a hung symbol() RPC call must never stall pool inserts). A separate task polls for tokens with NULL symbols and fills them in, writing "" as a sentinel on failure so broken tokens don't get retried on every
   pass.
4. HTTP API surface: list pools (cursor-paginated), lookup pools by address list (bulk), fetch ticks for one pool, fetch ticks for many pools (bulk grouped by address). These shapes exactly mirror the two queries the driver currently makes against the subgraph, so the swap-in is a minimal trait impl.

Driver integration. Behind a new V3PoolDataSource trait, the existing UniV3SubgraphClient and a new PoolIndexerClient are interchangeable. Config grows an optional pool-indexer-url; when set, it's used instead of the subgraph. The rest of the driver's V3 machinery (checkpoint, event replay, merge on new
blocks) is unchanged — pool-indexer just plugs in as the source of truth for initial + on-demand pool snapshots. Per-network switchover is one config line, fully backward compatible.

How to test

Added E2E tests.

I also deployed this to mainnet staging and did a swap and baseline participated. I did a bunch of smoke test that compare the results to the subgraph results and they were identical.